File        : HPC
Date        : 07-Dec-97
Author      :  A.Thoukydides, 1995, 1996, 1997
Description : High-level Procedure Call (HPC) services implemented by the
              ARMEdit module.


INTRODUCTION

The ARMEdit module provides a number of HPC services. To allow development to
start before HPC is included in the PC front-end software, and to support
earlier releases of the front-end software, a simplified interface via I/O
ports is also supported.

All of the services in this document use the HPC service identifier &105
which has been allocated by Aleph One.


I/O PORT ACCESS

The following I/O port assignments are currently used:

    &2E0    PORT_STATUS Word read
    &2E0    PORT_CMD    Word write
    &2E2    PORT_DATA   Byte or word read/write

The following sequence of operations should occur to perform an HPC call:

    Read PORT_STATUS. The possible return codes are:
    
        &454D   System is available and ready.

        &4D45   System is currently busy processing another HPC call, and
                cannot currently be used for another call.

        Any other code indicates that the service is not available.

    Write &0000 to PORT_CMD to start transfer of data.

    Write the HPC packet data to PORT_DATA as either bytes or words.

    Write &0001 to PORT_CMD to perform the HPC call.
    
    Write &0002 to PORT_CMD to start reading the reply.
    
    Read the HPC reply packet from PORT_DATA as either bytes or words.
    
    Write &0003 to PORT_CMD to reset the HPC system.

The port based HPC packets have the same 16384 byte limit that proper HPC
packets have.

Note that only HPC services provided by the ARMEdit module can be called
using this I/O port system; other services can only be called via the normal
HPC system. However, the HPC identifier is still checked.


HPC CALLS

For details of making HPC calls directly (which is potentially much more
efficient) contact Aleph One, as the information is covered by a Non
Disclosure Agreement.


RETURN CODES

All of the HPC calls place a 4 byte return code at the start of the return
block. The generic values are

    &0000   The operation was successful.

    &0001   The operation failed. The exact meaning of this depends upon the
            reason code, but in general it indicates that the rest of the
            return block is invalid.
    
    &FFFF   Service or reason code is unknown.

See the individual reason codes for details of any other codes returned, and
any contents of the remainder of the return block.


HPC_ARMEDIT_SWI

    Calls a specified RISC OS SWI by number. The SWI is always called with
    the X (error returning) bit set.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0000.
        4       4       SWI number.
        8       40      Values for registers R0 to R9 on entry to the SWI.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       256     RISC OS style error block returned by SWI if the
                        return code is &0001.
        260     40      Values of registers R0 to R9 on exit from the SWI if
                        the return code is &0000.


HPC_ARMEDIT_READ

    Read ARM memory.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0001.
        4       4       Start address of memory to read.
        8       4       Number of bytes to read. (n <= 16380)

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       n       The contents of the specified memory.


HPC_ARMEDIT_WRITE

    Write ARM memory.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0002.
        4       4       Start address of memory to read.
        8       4       Number of bytes to write. (n <= 16372)
        12      n       The data to write.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_ALLOC

    Claim a block of ARM memory. This is automatically released when the PC
    is shutdown or reset, but it is better to free it when no longer required
    using HPC_ARMEDIT_FREE.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0003.
        4       4       Amount of memory to claim.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       Address of the block of memory allocated.


HPC_ARMEDIT_FREE

    Release a block of ARM memory previously claimed using HPC_ARMEDIT_ALLOC.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0004.
        4       4       The address of the block of memory.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_EXTTYPE

    Convert a DOS extension into a RISC OS filetype.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0005.
        4       4       The extension in upper case padded with 0 bytes to
                        four characters.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       The RISC OS filetype.


HPC_ARMEDIT_TYPEEXT

    Convert a RISC OS filetype into a DOS extension.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0006.
        4       4       The RISC OS filetype.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       The extension in upper case padded with 0 bytes to
                        four characters.


HPC_ARMEDIT_FOPEN

    Open a RISC OS file. This is automatically closed when the PC is shutdown
    or reset, but it is better to close it when no longer required using
    HPC_ARMEDIT_CLOSE. A file opened using this call should not be closed
    using RISC OS routines directly.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0007.
        4       4       -1 to open existing file, or initial size of file to
                        create a new one.
        8       4       Non-zero to automatically delete file when closed.
        12      n       Name of file to open.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       RISC OS file handle.


HPC_ARMEDIT_FCLOSE

    Close a RISC OS file previously opened using HPC_ARMEDIT_OPEN. The file
    is deleted if specified when the file was opened.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0008.
        4       4       RISC OS file handle.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_FREAD

    Read from a RISC OS file.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0009.
        4       4       RISC OS file handle.
        8       4       Sequential file pointer for start of block, or -1 for
                        current position.
        12      4       Number of bytes to read.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       Number of bytes read.
        8       n       The data read from the file.


HPC_ARMEDIT_FWRITE

    Write to a RISC OS file.
        
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &000A.
        4       4       RISC OS file handle.
        8       4       Sequential file pointer for start of block, or -1 for
                        current position.
        12      4       Number of bytes to write.
        16      n       The data to write to the file.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_TALK_START

    Register a new client task. Note that a client ID of 0 is assumed.
    It does not make sense being able to request notification of reset or
    shutdown.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &000B.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       A unique client handle.


HPC_ARMEDIT_TALK_END

    Deregister a client task.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &000C.
        4       4       The previously assigned handle for this client task.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        

HPC_ARMEDIT_TALK_TX

    Send a message to another client task.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &000D.
        4       4       Client handle for this task.
        8       4       Either the ID or client handle for the recipient.
        12      1024    The message to send.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.

         HPC_ARMEDIT_TALK_RX

    Check for any waiting messages for this client task. The return code is
    failure if there is no message waiting. There is no acknowledge call
    since all messages to PC software should be addressed to a particular
    handle.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &000E.
        4       4       Client handle for this task.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       Source ID.
        8       4       Source client handle.
        12      1024    The waiting message.


HPC_ARMEDIT_DEVICE_INITIALISE

    Called during initialisation of device driver to obtain a start-up
    banner message and choose the number of devices.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &000F.
        4       1       Drive number for first unit of this driver.
        5       256     Text after equals sign on CONFIG.SYS line that loaded
                        this driver.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       Number of devices supported.
        8       256     Text of message terminated by a "$" character.


HPC_ARMEDIT_DEVICE_BPB

    Construct a BIOS Parameter Block (BPB) for a device driver. This also
    informs ARMEdit that the disc contents could be changed.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0010.
        4       1       Unit code (drive number), or -1 for initialisation.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       13      The BIOS parameter block.


HPC_ARMEDIT_DEVICE_CHANGED

    Perform a media check for a device driver.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0011.
        4       1       Unit code (drive number).
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       The media change code:
                            -1  Disc has been changed.
                            0   Don't know if disc has been changed.
                            1   Disc has not been changed.


HPC_ARMEDIT_DEVICE_READ
    
    Read an emulated disc sector for a device driver.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0012.
        4       1       Unit code (drive number).
        5       2       Sector number.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       n       The data read from the sector.


HPC_ARMEDIT_DEVICE_WRITE
    
    Write an emulated disc sector for a device driver.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0013.
        4       1       Unit code (drive number).
        5       2       Sector number.
        7       1       Dummy data to pad to word boundary.
        8       n       The data to write to the sector.
    
    Data returned:
    
        Offset  Size    Description

        0       4       Return code.


HPC_ARMEDIT_DATE_TO_DOS

    Convert a time and date from the standard RISC OS 5 bytes format to the
    4 byte DOS equivalent.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0014.
        4       5       Centiseconds since 00:00:00 on January 1 1900.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       2 byte time (hhhhhmmmmmmsssss).
        8       4       2 byte date (yyyyyyymmmmddddd).
    

HPC_ARMEDIT_DATE_TO_RISCOS

    Convert a time and date from the standard DOS 4 byte format to the 5 byte
    RISC OS equivalent.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0015.
        4       2       2 byte time (hhhhhmmmmmmsssss).
        6       2       2 byte date (yyyyyyymmmmddddd).
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       5       Centiseconds since 00:00:00 on January 1 1900.


HPC_ARMEDIT_OSCLI_START

    Start executing a specified *command. The input and output from the
    command are redirected.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0016.
        4       256     The command to execute.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       Handle for this command.


HPC_ARMEDIT_OSCLI_POLL

    Continue execution of a *command. This should only include input data if
    requested by the previous HPC_ARMEDIT_OSCLI_POLL reply, otherwise
    characters may get lost.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0017.
        4       4       Command handle.
        8       4       Number of bytes to input.
        12      256     Up to 256 bytes of input.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       Status:
                            0   Active.
                            1   Command has finished.
                            2   Waiting for input.
        8       4       Number of bytes to output.
        12      256     Up to 256 bytes of output.


HPC_ARMEDIT_OSCLI_END

    Terminate execution of a *command.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0018.
        4       4       Command handle.

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       256     RISC OS style error block returned by the command if
                        the return code is &0001.
        

HPC_ARMEDIT_TALK_REPLY

    Reply to a message from another client task. This is like
    HPC_ARMEDIT_TALK_TX, except that the message is stored in the destination
    task's buffer.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0019.
        4       4       Client handle for this task.
        8       4       The client handle for the recipient.
        12      1024    The message to send.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_FASTER

    Prevent multitasking to speed up operations. This should be called to
    reenable normal operation after the operation is completed. A sensible
    way to use this is with a value of 100 (for 1 second), called on a
    regular basis during the operation.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &001A.
        4       4       Centiseconds to disable multitasking for, or 0 to
                        restore normal operation.
        
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_TEMPORARY

    Produce a unique filename for a temporary RISC OS file.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &001B.
        
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       256     Suggested canonicalised filename.


HPC_ARMEDIT_DEVICE_READ_LONG
    
    Read an emulated disc sector for a device driver with a 32bit sector
    number.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &001C.
        4       1       Unit code (drive number).
        5       3       Dummy data to pad to word boundary.
        8       4       Sector number.
    
    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       n       The data read from the sector.


HPC_ARMEDIT_DEVICE_WRITE_LONG
    
    Write an emulated disc sector for a device driver with a 32bit sector
    number.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &001D.
        4       1       Unit code (drive number).
        5       3       Dummy data to pad to word boundary.
        8       4       Sector number.
        12      n       The data to write to the sector.
    
    Data returned:
    
        Offset  Size    Description

        0       4       Return code.


HPC_ARMEDIT_DEVICE_OPEN

    A file is being opened on the device.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &001E.
        4       1       Unit code (drive number).

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_DEVICE_CLOSE

    A file is being closed on the device.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &001F.
        4       1       Unit code (drive number).

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.


HPC_ARMEDIT_DEVICE_REMOVABLE

    Check if a device is removable.
    
    Data sent:
    
        Offset  Size    Description
        
        0       2       HPC service ID.
        2       2       Reason code = &0020.
        4       1       Unit code (drive number).

    Data returned:
    
        Offset  Size    Description
        
        0       4       Return code.
        4       4       The removable device status:
                            &0000   Removable
                            &0200   Nonremovable


THINGS TO DO

The following are changes that may be made to the HPC services sometime in
the future.

    None at the moment!


VERSION HISTORY

0.00 (12-Nov-95)    Original development version.

0.01 (14-Nov-95)    No changes to HPC.

0.02 (15-Nov-95)    No changes to HPC.

0.03 (17-Nov-95)    Uses correct HPC service identifier.

0.04 (21-Nov-95)    Slightly more experimental device driver support.
                    Real HPC system implemented.

0.07 (28-Dec-95)    Added message passing protocol.

1.00 (15-Dec-95)    First official release version.

1.01 (11-Mar-96)    Version number updated to match the module.

1.02 (27-May-96)    Implemented device driver calls.
                    Added commands to convert between date and time formats.
                    Included SWI for use by Acorn's software PC emulator.

1.03 (21-Feb-97)    Added ability to reply to messages.
                    Included ability to speed up operations when multitasking.
                    Temporary RISC OS filenames can now be generated.

1.04 (07-Dec-97)    Added device driver operations for 32bit sector numbers.
                    Included device driver support for removable media.